.TH PYJSBUILD 1 "April 28, 2009"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
pyjsbuild \- builds a web application
.SH SYNOPSIS
.B pyjsbuild
.RI [ options ] application
.br
.SH DESCRIPTION
This manual page documents briefly the
.B pyjsbuild
command.
.PP
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
.\" respectively.
\fBpyjsbuild\fP is a program that compiles python (pyjamas) web applications
into javascript, automatically adding suitable boilerplate, "loader"
infrastructure and run-time libraries, for detection and support of all major
web browsers.  Typical usage is simply "pyjsbuild {Application}.py" and the
compiled application will be created in a subdirectory called "output".
If a subdirectory called "public" exists in the same directory in which
pyjsbuild is run, its contents will be copied verbatim and recursively
into the "output" directory.
.sp
To load the compiled application, as usual for any web application,
simply point the web browser at the {Application}.html file, which
can be found in the output directory.  If at compile-time a file
named {Application}.html was not found in the same directory as
{Application}.py or in the "public" folder, pyjsbuild will create
a stub html file, automatically.
.sp
As applications are expected to run in a web browser as javascript,
the "standard" python libraries are \fBnot\fP accessible to the
web application.  Hence, the pyjamas framework provides independent
reimplementations of standard python builtins, types and libraries
(that are written in, or compiled to, javascript, along with the
rest of the application).  It is essential that a developer not
confuse standard python libraries with the pyjamas libraries if
the \-I option is used to specify additional library paths.
.SH OPTIONS
These programs follow the usual GNU command line syntax, with long
options starting with two dashes (`-').
A summary of options is included below.
.TP
.B \-h, \-\-help
Show summary of options.
.TP
.B \-v, \-\-version
Show version of program.
.TP
.B \-o OUTPUT, --output=OUTPUT
directory to which the webapp should be written
.TP
.B \-j JS_INCLUDES, --include-js=JS_INCLUDES
javascripts to load into the same frame as the rest of the script
.TP
.B \-I LIBRARY_DIRS, --library_dir=LIBRARY_DIRS
additional paths appended to PYJSPATH
.TP
.B \-D DATA_DIR, --data_dir=DATA_DIR
path for data directory
.TP
.B \-m, --dynamic-modules
Split output into separate dynamically-loaded modules (experimental)
.TP
.B \-P PLATFORMS, --platforms=PLATFORMS
platforms to build for, comma-separated (default is all)
.TP
.B \-d, --debug           
.TP
.B \-O, --optimize
Optimize generated code (removes all print statements)
.TP
.B \-c, --cache_buster
Enable browser cache-busting (MD5 hash added to output filenames)
.SH PLATFORM SUPPORT
Supported platforms are IE6, Mozilla, Safari, OldMoz and Opera.
The \-P option allows a subset of platforms to be compiled, if
desired.  Platform support is done by looking for platform-specific
"overrides" in a subdirectory called "platform".  So, if the application
is called "Hello.py", and there exists a file "platform/HelloIE6.py"
then any functions or classes in HelloIE6.py will "override" any such
functions or classes in the "Hello.py" module, specifically when
the code for the IE6 platform is compiled.
.sp
There are plenty of examples and instances throughout the pyjamas
libraries where platform-overrides are used (for example, the
BrowserDetect.py example).  Note that because pyjamas takes care
of "merging" the platform-specific overrides in each module,
it is not necessary to override an entire class: only make
alternatives for those functions or class methods which absolutely
need replacing on a per-platform basis, and it is good practice
to split the application design into functions and classes where
as few platform-specific lines of code as possible go into the
platform-specific overrides.
.SH CACHE BUSTING
Browsers, Web Servers and Web Frameworks have a nasty habit of
cacheing HTML and Javascript files, which throws a spanner in
the works of rapid application development as the developer has
to clear the browsers' cache, delete the HTTP proxy cache, locate
and delete the Web Framework's cache (e.g. Joomla), clear the Web
Browser cache, restart the web server, restart the web browser etc.
To help avoid such stupidities, use the \-c option to add a unique
MD5 hash to the end of all output filenames.  The MD5 hash that is
appended is the MD5 hash of the contents of each file.
.SH OPTIMISATION
\fBpyjsbuild\fP is \fBnot\fP a javascript compressor, it is a
compiler.  Use \-m to enable dynamic (shared) modules if space is
at a premium, or consider running the javascript through a standard
javascript compressor such as YUI Compressor.  Also bear in mind
that the \-d option increases the size of the compiled javascript
by four to five times, so do not use \-d for release builds.
.SH DEBUGGING
\fBpyjsbuild\fP is \fBnot\fP an interpreter, it is a compiler,
and the resultant javascript output will be interpreted by the
web browser, not the standard python interpreter.  It is worth
emphasising this because python developers who are expecting
pyjsbuild to perform all the usual tricks that the standard python
interpreter performs are in for a bit of a shock.  Therefore, just
as with all Web 2.0 Javascript applications, debugging needs to
be done using \fBjavascript\fP tools, such as the Microsoft Script
Debugger for IE, and Firebug and Venkman for Firefox (use of both
is thoroughly recommended).  However, there are circumstances where
script debugging is either impossible or inconvenient.  For that,
there is the "-d" option which, whilst not perfect, provides a
reasonable approximation of python run-time stack trace exception
handling.
.SH SEE ALSO
.BR pyjscompile (1),
.BR http://pyjs.org
.SH AUTHOR
pyjamas was written by Luke Kenneth Casson Leighton <lkcl@lkcl.net>,
James Tauber and others.  It originated from a port of Google Web Toolkit,
which is Copyright Google, Inc.
.PP
This manual page was written by Luke Kenneth Casson Leighton <lkcl@lkcl.net>,
for the Debian project (but may be used by others).
